监控 Kubernetes 集群的服务器和应用使用OneAgent定制探针版本

最后于 2024年9月12日 更新

APO 分为两部分：

APO-server： APO 服务侧组件
APO-one-agent： APO 用户侧组件，用于采集Kubernetes集群或者虚机环境下被监控业务以及集群、主机信息。

本文档包含配置 APO-one-agent 自定义 Java 探针，并使用使用 Helm Chart 在 Kubernetes 上安装和运行定制版镜像 APO-one-agent 的说明。请确保在安装 APO-one-agent 之前，您已经安装 APO-server。

注意： 不建议用本文档的安装方式将 APO-server 与 APO-one-agnet 安装在同一 Kubernetes 集群中，会产生不必要的资源浪费；如果想要将 APO-server 与 APO-one-agent 部署在同一 Kubernetes 集群中，请参考快速开始文档

注意： 使用默认探针版本的 APO-one-agent ，可以根据监控 Kubernetes 集群中的服务器和应用使用OneAgent默认OTEL探针版本

APO-one-agent 内置各个编程语言的默认采集探针版本：

Java agent: opentelemetry-java-instrumentation v2.5.0
Python agent: opentelemetry-python 1.23.0/0.44b0
NodeJs agent: opentelemetry-js v1.24.1/0.51.1
Go agent: opentelemetry-go-instrumentation v0.13.0-alpha

注意： 目前只推荐使用 Skywalking 或者 OpenTelemetry 的 Java 探针；暂不支持除 Java 以外的语言的探针替换。

如何替换 APO-one-agent 中的 Java 探针

针对 Java 应用，APO-one-agent 默认集成了以下版本 Java 探针：

Opentelemetry v2.5.0（默认）

本文档介绍如何在安装 APO-one-agent 时使用其他 Java 探针版本。

如果默认集成的探针版本不满足你的需求，参考下面的步骤构建自定义的 APO-one-agent 中的探针镜像；这样你可以使用比如 Skywalking v9.2.0 或 Opentelemetry v2.2.0 之类的其他版本探针。

1. 下载 OneAgent builder 模版

下载地址: https://apo-ce.oss-cn-hangzhou.aliyuncs.com/preload-builder.zip

模版的文件目录结构如下：

preload-builder
├── opentelemetry-java
│   ├── Dockerfile
│   ├── libapoinstrument.conf
│   └── opentelemetry
│       └── opentelemetry-javaagent.jar
└── skywalking-java
    ├── Dockerfile
    ├── libapoinstrument.conf
    └── skywalking-agent
        ├── ...
        └── skywalking-agent.jar

2. 替换探针文件

注意: 你只需要替换自己需要的探针,不需要同时替换OTEL和Skywalking的探针

OTEL探针

OTEL的JAVA探针以单个Jar包的方式提供。

使用需要的版本的OTEL探针替换模版目录中的 opentelemetry-java/opentelemetry/opentelemetry-javaagent.jar 文件, 注意不要更改文件名。

Skywalking探针

从Skywalking官网获得的探针文件通常是一个包含有 skywalking-agent.jar 和其配置文件的文件夹;

推荐的做法是移除模版中的 skywalking-java/skywalking-agent 目录, 随后用官网下载的探针文件进行替换;

这是因为不同版本的 skywalking-agent.jar 和其他文件可能不兼容, 完整替换是最安全的。

注意替换后不要更改skywalking-java/skywalking-agent/skywalking-agent.jar的文件名.

3. 构建镜像

如果使用的是自定义的OTEL探针

使用下面的脚本来进行探针构建

cd opentelemetry-java
docker build -t registry.cn-hangzhou.aliyuncs.com/originx/odigos-odiglet:latest-custom .

如果使用的是自定义的Skywalking探针

使用下面的脚本来进行探针构建

cd skywalking-java
docker build -t registry.cn-hangzhou.aliyuncs.com/originx/odigos-odiglet:latest-custom .

4. 同步镜像文件到机器

你需要将构建好的镜像文件推送到可用的Harbor仓库,或者手动同步到机器.

推送到Harbor仓库(注意将脚本中的HARBOR_REGISTRY修改为仓库地址)

HARBOR_REGISTRY=#修改为仓库地址

docker tag registry.cn-hangzhou.aliyuncs.com/originx/odigos-odiglet $HARBOR_REGISTRY/originx/odigos-odiglet:latest-custom
docker push $HARBOR_REGISTRY/originx/odigos-odiglet:latest-custom

手动同步到机器

docker save registry.cn-hangzhou.aliyuncs.com/originx/odigos-odiglet:latest-custom | gzip > apo-odiglet.tgz

将生成的文件复制到后续部署探针的机器上(如果是K8s环境需要复制到每个节点上) 在每个节点上执行下面的命令加载镜像

gunzip -c apo-odiglet.tgz | docker load

5. 安装时使用新构建的镜像

完成上面的镜像推送步骤,你会获得一个可用的探针镜像版本:

如果你使用Harbor,后续使用$HARBOR_REGISTRY/originx/odigos-odiglet:latest-custom, 注意$HARBOR_REGISTRY修改为你的仓库地址
如果你是手动推送的,后续使用 registry.cn-hangzhou.aliyuncs.com/originx/odigos-odiglet:latest-custom

安装准备工作

使用 Helm 安装 APO，请确保已完成以下操作：

在计算机上安装 Kubernetes 服务器。有关安装 Kubernetes 的信息，请参阅安装 Kubernetes。
安装 Helm 的最新稳定版本。有关安装 Helm 的信息，请参阅安装 Helm。
网络策略：需要 APO-one-agent 所在集群/机器能够访问 APO-server 集群的 31363、30428、31317 端口。

设置 APO Helm 仓库

要设置 APO Helm 存储库，以便在计算机上下载正确的 APO Helm charts，请完成以下步骤： 使用下方命令添加 apo Helm 仓库

helm repo add apo https://apo-charts.oss-cn-hangzhou.aliyuncs.com
helm repo update apo

K8s 环境安装

安装 APO-one-agent 时,使用下面的参数以指定使用您的自定义版本镜像：在安装前修改配置文件，更换配置中的镜像名以及tag

# apoServerIP 为 APO-server 所在的 ClusterIP
global:
  apoServerIP: x.x.x.x # FIXME

# APO-one-agent enabled标志位，默认为 false
odigos:
  config:
    javaAgentType: otherveriosns
  instrumentor:
    # targetNamespace 
    # name：目标命名空间
    # value：
    #   enabled: 注入现有的所有服务,但不注入后续新增应用
    #   enabledFuture: 注入现在以及后续的所有服务
    #   disabled: 不注入指定namespace下的服务,用于在instrument-all-namespace时忽略特定的Namespace
    targetNamespace:
    - name: default
      value: enabledFuture
    - name: default2
      value: enabled
    - name: default3
      value: disabled
    # instrument-all-namespace 是否注入所有namespace
    # 等价于设置所有namespace的enabledFuture
    # 但如果已经设置了ns或者workload的disabled将不会注入
    instrumentAllNamespace: false
    # force-instrument-all-namespace 是否强制注入所有namespace
    # 和instrument-all-namespace类似,所有ns设置enabledFuture
    # 并忽略所有disabled设置
    forceInstrumentAllNamespace: false

# 如果您的自定义探针为skywalking版本，请加上这段配置
# apoOneAgent:
#   config:
#     javaAgentType: "skywalking"

odiglet:
  image:
    repository: "registry.cn-hangzhou.aliyuncs.com/originx/apo-odiglet" # FIXME
    tag: "latest-custom" # FIXME 本文档打包默认tag为latest-custom，如果您打包时tag有修改，请同步为您的自定义tag

这里提供的为 APO 部署的基础配置，如果您要进行更多配置更改，请从 APO Helm Charts 库中下载values.yaml文件：

helm show values apo/apo-one-agent > values.yaml

部署 APO-one-agent

运行以下命令，在指定命名空间中部署 APO 。

helm install apo-one-agent apo/apo-one-agent -n apo --create-namespace \
-f apo-one-agent-values.yaml

验证

见到类似输出既代表安装成功

NAME: apo-one-agent
LAST DEPLOYED: Fri Aug  9 09:33:16 2024
NAMESPACE: apo
STATUS: deployed
REVISION: 1
NOTES:
=======================================
      ___           ___           ___
     /\  \         /\  \         /\  \
    /::\  \       /::\  \       /::\  \
   /:/\:\  \     /:/\:\  \     /:/\:\  \
  /::\~\:\  \   /::\~\:\  \   /:/  \:\  \
 /:/\:\ \:\__\ /:/\:\ \:\__\ /:/__/ \:\__\
 \/__\:\/:/  / \/__\:\/:/  / \:\  \ /:/  /
      \::/  /       \::/  /   \:\  /:/  /
      /:/  /         \/__/     \:\/:/  /
     /:/  /                     \::/  /
     \/__/                       \/__/
Official Website: https://apo.kindlingx.com/

输入下方命令检查pod是否启动成功

kubectl get po -n apo

# 您应该看到类似于以下内容的输出
NAME                                                 READY   STATUS    RESTARTS      AGE
apo-odigos-instrumentor-7f96957cb6-6sq2r             1/1     Running   0             5m
apo-one-agent-vbkzl                                  7/7     Running   0             5m
apo-otel-collector-85bdfd5898-fgcbf                  1/1     Running   0             5m

卸载 APO-one-agent

helm uninstall apo-one-agent -n apo
kubectl delete ns apo

探针配置变更(高级功能)

注意: 如果你没有修改配置的需求,可以跳过这一部分. APO和提供的模版已经配置好了基础参数.

在大多数时候,你不需要考虑探针的配置问题, preload通过一定的逻辑为探针配置了必须的两个参数:

服务名 (OTEL_SERVICE_NAME/SW_AGENT_NAME): 由 jar 包或主类名生成
数据发送地址 (OTEL_EXPORTER_OTLP_ENDPOINT/ SW_AGENT_COLLECTOR_BACKEND_SERVICES): 由 apo 的部署文件进行维护

其余参数均使用探针的自身的默认配置

如果需要修改默认参数, 可以参考下面的内容修改模版中对应的libapoinstrument.conf文件以下面的示例模版为例, 每个模版中包含三个文件或目录, 其中AAAA/BBBB都是泛指,即不限定文件名:

Dockerfile: 决定了要更新preload-agent镜像中的哪些文件,通常不需要修改
libapoinstrument.conf: 决定了使用探针时的配置
BBBB目录: 包含自定义探针的可执行文件和自带配置

preload-builder
└── AAAA
    ├── Dockerfile
    ├── libapoinstrument.conf
    └── BBBB
        └── CCCC.jar

构建镜像时

AAAA目录下的所有文件将被复制到镜像的/etc/apo/instrumentations/custom/目录下;
libapoinstrument.conf中的所有配置会替换镜像中已有的配置.

libapoinstrument.conf 配置说明

以 opentelemetry 的配置为例, 模版中的的配置文件如下:

[java]
OTEL_SERVICE_NAME={{APO_AUTO_SERVICE_NAME}}
OTEL_EXPORTER_OTLP_ENDPOINT= {{APO_COLLECTOR_GRPC_ENDPOINT}}
JAVA_TOOL_OPTIONS=-javaagent:/etc/apo/instrumentations/custom/opentelemetry/opentelemetry-javaagent.jar
JAVA_OPTS=-javaagent:/etc/apo/instrumentations/custom/opentelemetry/opentelemetry-javaagent.jar
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
OTEL_TRACES_SAMPLER=always_on
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=none
OTEL_LOGS_EXPORTER=none

下面是配置的说明:

[java] 作为一小节的开头,标识本节的所有配置作为java程序启动时自动注入的环境变量; 目前支持 java/python/nodejs/dotnet 四种语言
OTEL_SERVICE_NAME={{APO_AUTO_SERVICE_NAME}}, 因为服务名信息需要在应用启动时动态生成,所以使用APO提供的动态变量{{APO_AUTO_SERVICE_NAME}}来替换.可用的动态参数如下
- APO_AUTO_SERVICE_NAME: 自动发现服务名,目前仅支持JAVA,python/nodejs/dotnet会用对应的语言名作为APO_AUTO_SERVICE_NAME
- APO_COLLECTOR_GRPC_ENDPOINT APO的OtelCollector地址,接收otlp协议数据
- APO_COLLECTOR_HTTP_ENDPOINT 同上,接收otlphttp协议数据
- APO_COLLECTOR_SKYWALKING_ENDPOINT 同上,接收skywalking协议数据
JAVA_TOOL_OPTIONS=-javaagent:/etc/apo/instrumentations/custom/BBBB/CCCC.jar, 因为模版目录下的文件全部会复制到镜像的/etc/apo/instrumentations/custom/目录下,所以用这个绝对路径来指定探针的文件
其他参数为静态参数,将直接作为环境变量添加到程序启动, 下面的文档提供了如何使用环境变量设置探针参数

OTEL的自定义配置参考下面的文档 Configuration

Skywalking的自定义配置参考下面的文档 Setting Override

如何替换 APO-one-agent 中的 Java 探针​

1. 下载 OneAgent builder 模版​

2. 替换探针文件​

OTEL探针​

Skywalking探针​

3. 构建镜像​

如果使用的是自定义的OTEL探针​

如果使用的是自定义的Skywalking探针​

4. 同步镜像文件到机器​

5. 安装时使用新构建的镜像​

安装准备工作​

设置 APO Helm 仓库​

K8s 环境安装​

部署 APO-one-agent​

验证​

卸载 APO-one-agent​

探针配置变更(高级功能)​

libapoinstrument.conf 配置说明​